<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Defining a Special Function.</title>
<link rel="stylesheet" href="../../../../multiprecision.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../fp_eg.html" title="Examples">
<link rel="prev" href="caveats.html" title="Drop-in Caveats">
<link rel="next" href="nd.html" title="Calculating a Derivative">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="caveats.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_eg.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nd.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="boost_multiprecision.tut.floats.fp_eg.jel"></a><a class="link" href="jel.html" title="Defining a Special Function.">Defining
          a Special Function.</a>
</h5></div></div></div>
<p>
            In this example we'll show several implementations of the <a href="http://mathworld.wolfram.com/LambdaFunction.html" target="_top">Jahnke
            and Emden Lambda function</a>, each implementation a little more
            sophisticated than the last.
          </p>
<p>
            The Jahnke-Emden Lambda function is defined by the equation:
          </p>
<div class="blockquote"><blockquote class="blockquote"><p>
              <span class="emphasis"><em>JahnkeEmden(v, z) = Γ(v+1) * J<sub>v</sub>(z) / (z / 2)<sup>v</sup></em></span>
            </p></blockquote></div>
<p>
            If we were to implement this at double precision using Boost.Math's facilities
            for the Gamma and Bessel function calls it would look like this:
          </p>
<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">JEL1</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">v</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
   <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span><span class="special">(</span><span class="identifier">z</span> <span class="special">/</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
            Calling this function as:
          </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">JEL1</span><span class="special">(</span><span class="number">2.5</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
            Yields the output:
          </p>
<pre class="programlisting">9.822663964796047e-001</pre>
<p>
            Now let's implement the function again, but this time using the multiprecision
            type <code class="computeroutput"><span class="identifier">cpp_dec_float_50</span></code>
            as the argument type:
          </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_dec_float_50</span>
   <span class="identifier">JEL2</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_dec_float_50</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_dec_float_50</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
   <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">pow</span><span class="special">(</span><span class="identifier">z</span> <span class="special">/</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
            The implementation is almost the same as before, but with one key difference
            - we can no longer call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span></code>,
            instead we must call the version inside the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span></code>
            namespace. In point of fact, we could have omitted the namespace prefix
            on the call to <code class="computeroutput"><span class="identifier">pow</span></code> since
            the right overload would have been found via <a href="http://en.wikipedia.org/wiki/Argument-dependent_name_lookup" target="_top">argument
            dependent lookup</a> in any case.
          </p>
<p>
            Note also that the first argument to <code class="computeroutput"><span class="identifier">pow</span></code>
            along with the argument to <code class="computeroutput"><span class="identifier">tgamma</span></code>
            in the above code are actually expression templates. The <code class="computeroutput"><span class="identifier">pow</span></code> and <code class="computeroutput"><span class="identifier">tgamma</span></code>
            functions will handle these arguments just fine.
          </p>
<p>
            Here's an example of how the function may be called:
          </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">JEL2</span><span class="special">(</span><span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="number">2.5</span><span class="special">),</span> <span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="number">0.5</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
            Which outputs:
          </p>
<pre class="programlisting">9.82266396479604757017335009796882833995903762577173e-01</pre>
<p>
            Now that we've seen some non-template examples, lets repeat the code
            again, but this time as a template that can be called either with a builtin
            type (<code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> etc), or with a multiprecision
            type:
          </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Float</span><span class="special">&gt;</span>
<span class="identifier">Float</span> <span class="identifier">JEL3</span><span class="special">(</span><span class="identifier">Float</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">Float</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span><span class="special">;</span>
   <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">z</span> <span class="special">/</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
            Once again the code is almost the same as before, but the call to <code class="computeroutput"><span class="identifier">pow</span></code> has changed yet again. We need
            the call to resolve to either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span></code>
            (when the argument is a builtin type), or to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">pow</span></code>
            (when the argument is a multiprecision type). We do that by making the
            call unqualified so that versions of <code class="computeroutput"><span class="identifier">pow</span></code>
            defined in the same namespace as type <code class="computeroutput"><span class="identifier">Float</span></code>
            are found via argument dependent lookup, while the <code class="computeroutput"><span class="keyword">using</span>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span></code> directive makes the standard library
            versions visible for builtin floating point types.
          </p>
<p>
            Let's call the function with both <code class="computeroutput"><span class="keyword">double</span></code>
            and multiprecision arguments:
          </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">JEL3</span><span class="special">(</span><span class="number">2.5</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">JEL3</span><span class="special">(</span><span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="number">2.5</span><span class="special">),</span> <span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="number">0.5</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
            Which outputs:
          </p>
<pre class="programlisting">9.822663964796047e-001
9.82266396479604757017335009796882833995903762577173e-01
</pre>
<p>
            Unfortunately there is a problem with this version: if we were to call
            it like this:
          </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_dec_float_50</span> <span class="identifier">v</span><span class="special">(</span><span class="number">2</span><span class="special">),</span> <span class="identifier">z</span><span class="special">(</span><span class="number">0.5</span><span class="special">);</span>
<span class="identifier">JEL3</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">0.5</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span>
</pre>
<p>
            Then we would get a long and inscrutable error message from the compiler:
            the problem here is that the first argument to <code class="computeroutput"><span class="identifier">JEL3</span></code>
            is not a number type, but an expression template. We could obviously
            add a typecast to fix the issue:
          </p>
<pre class="programlisting"><span class="identifier">JEL</span><span class="special">(</span><span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">0.5</span><span class="special">),</span> <span class="identifier">z</span><span class="special">);</span>
</pre>
<p>
            However, if we want the function JEL to be truly reusable, then a better
            solution might be preferred. To achieve this we can borrow some code
            from Boost.Math which calculates the return type of mixed-argument functions,
            here's how the new code looks now:
          </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Float1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Float2</span><span class="special">&gt;</span>
<span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">Float1</span><span class="special">,</span> <span class="identifier">Float2</span><span class="special">&gt;::</span><span class="identifier">type</span>
   <span class="identifier">JEL4</span><span class="special">(</span><span class="identifier">Float1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">Float2</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span><span class="special">;</span>
   <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">z</span> <span class="special">/</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
            As you can see the two arguments to the function are now separate template
            types, and the return type is computed using the <code class="computeroutput"><span class="identifier">promote_args</span></code>
            metafunction from Boost.Math.
          </p>
<p>
            Now we can call:
          </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_100</span><span class="special">&gt;::</span><span class="identifier">digits10</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">JEL4</span><span class="special">(</span><span class="identifier">cpp_dec_float_100</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">+</span> <span class="number">0.5</span><span class="special">,</span> <span class="identifier">cpp_dec_float_100</span><span class="special">(</span><span class="number">0.5</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
            And get 100 digits of output:
          </p>
<pre class="programlisting">9.8226639647960475701733500979688283399590376257717309069410413822165082248153638454147004236848917775e-01</pre>
<p>
            As a bonus, we can now call the function not just with expression templates,
            but with other mixed types as well: for example <code class="computeroutput"><span class="keyword">float</span></code>
            and <code class="computeroutput"><span class="keyword">double</span></code> or <code class="computeroutput"><span class="keyword">int</span></code> and <code class="computeroutput"><span class="keyword">double</span></code>,
            and the correct return type will be computed in each case.
          </p>
<p>
            Note that while in this case we didn't have to change the body of the
            function, in the general case any function like this which creates local
            variables internally would have to use <code class="computeroutput"><span class="identifier">promote_args</span></code>
            to work out what type those variables should be, for example:
          </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Float1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Float2</span><span class="special">&gt;</span>
<span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">Float1</span><span class="special">,</span> <span class="identifier">Float2</span><span class="special">&gt;::</span><span class="identifier">type</span>
   <span class="identifier">JEL5</span><span class="special">(</span><span class="identifier">Float1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">Float2</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span><span class="special">;</span>
   <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">Float1</span><span class="special">,</span> <span class="identifier">Float2</span><span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">variable_type</span><span class="special">;</span>
   <span class="identifier">variable_type</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">z</span> <span class="special">/</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
   <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">v</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">t</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2002-2020 John
      Maddock and Christopher Kormanyos<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="caveats.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_eg.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nd.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
